Document model pricing, the agent's per-session spend caps, and final cancels - #727

⊙ Problem

agent: carry per-call token usage onto the session and enforce a budget (HarperFast/harper#3040) enforces the agent's maxCostUsd, adds agent.maxSessionTokens, session usage and model pricing, and makes a cancel final. The reference still calls maxCostUsd "not enforced", with a 5.00 default.

Refs HarperFast/harper#3040. Companion to Cap the agent's spend per session by tokens or priced cost, record its model usage, and make a cancel final (HarperFast/harper#3177).

🤔 Should these docs merge with the core PR?

Yes. They cover new config keys, a new response field, and changed status, 409 and cancel behavior that clients key on. Dated v5.4.0 to match the core milestone.

💡 Solution

• Model pricing: a Pricing subsection, the pricing field, costUsd on GenerateResult, unpriced streaming, and maxCostUsd for toolMode: 'auto'.
• Agent spend caps: the maxSessionTokens and maxCostUsd options and a new Agent spend caps subsection: what a cap counts, when it is checked, and how a stop ends a session.
• Operations: usage on session reads, cap stops in status, agent_prompt's new 409s and their codes, at-most-once approved actions, and what a cancel does to approvals.
• Release notes: spend caps, cancellation and model pricing entries.

🔧 Changes

• runInFlight on session reads, the auto loop's maxToolTokens and maxCostUsd stopping it when they cannot be measured, and what a bare cap key does.
• set_agent_config's key list and settings captured at run start gain the caps; list_agent_sessions reports the same totals.
• The rejected-reply note in the 5.4 agent section now says such a reply counts toward the caps, and maxTurns is validated, a bare key failing the start.
• The api.md and tool-calling.md hunks also re-align their tables, which Prettier does when a wider row is added.

✅ Verification

• Every statement was checked against the core branch's code by cross-model review rounds.
• npm run format:check passes.
• The behavior these pages describe is exercised by the core PR's integrationTests/server/agent-budget.test.ts and its agent unit suites.

_{🤖 Generated by Claude Code (Anthropic Claude Opus 5.5); posted via @DavidCockerill.}

Related PRs: #712 overlaps (merged here; agent.maxTokens in the same agent options, set_agent_config text and 5.4 notes), #717 overlaps (merged here; agent.configScope in the same agent options and set_agent_config text), #720 overlaps (merged here; agent.maxToolResultBytes in the same agent options and set_agent_config text), 2 others independent
Complexity: medium

Deferred findings

• 6c2d1cefc7c6cd2c minor correctness — reference/configuration/options.md — Billed failed calls excluded from session caps — filed agent spend caps: count billed failed calls where possible, and recover a session one unmeasured call stranded harper#3295
• 1ca509ed904c3cac minor reliability — reference/configuration/options.md — One unmeasured call (pre-5.4 or a provider hiccup) strands a session under a cap — filed agent spend caps: count billed failed calls where possible, and recover a session one unmeasured call stranded harper#3295

_{Review-Coverage: authored=claude; ran=gemini,codex; adjudicated=domain; blocked=cursor-composer(not-installed); declined=cursor-grok,cursor-kimi,cursor-muse,muse; rounds=14; full=3 @ 569af46}

_{Review-Attention: skim ~2m (decisions: bare-cap-key-unsets, run-in-flight-node-local, structured-409-codes, auto-loop-unmeasured-fails-closed, session-scoped-budget, failed-calls-uncounted) @ 569af46}